﻿ניהול וטיפול בשגיאות
==============

Yii מספקת פריימוורק מלא עבור טיפול בשגיאות המבוססת על מנגנון החריגות (exceptions) ב PHP 5. ברגע שהאפליקציה נוצרת, בכדי לטפל בבקשות משתמשים נכנסות, היא רושמת את המתודה [handleError|CApplication::handleError] בכדי לטפל באזהרות והתראות של PHP; והיא רושמת את המתודה [handleException|CApplication::handleException] בכדי לטפל בחריגים (exceptions) שלא נתפסו.
כתוצאה מכך, במידה ותזרק שגיאה/אזהרה/התראה של PHP או שיזרק חריג (exception) שלא נתפס במהלך הרצת האפליקציה, אחד ממתודות ניהול השגיאות יכנסו לפעולה ויתחילו בתהליך טיפול בשגיאות.


» Tip|טיפ: הרישום של המתודות המטפלות בשגיאות נעשה בתהליך היצירה של האפליקציה על ידי קריאה לפונקציות PHP
[set_exception_handler](http://www.php.net/manual/en/function.set-exception-handler.php)
ו [set_error_handler](http://www.php.net/manual/en/function.set-error-handler.php).

אם אינך רוצה ש Yii יטפל בשגיאות, תוכל להגדיר את המשתנים הקבועים `YII_ENABLE_ERROR_HANDLER` ו `YII_ENABLE_EXCEPTION_HANDLER` לערך
false [בסקריפט הכניסה הראשי](/doc/guide/basics.entry).

כברירת מחדל, [errorHandler|CApplication::errorHandler] (או [exceptionHandler|CApplication::exceptionHandler]) מעלים את האירוע [onError|CApplication::onError] או [onException|CApplication::onException]. במידה והשגיאה לא מטופלת על ידי מנהל אירוע כלשהו שהוגדר לאירוע מסוג זה, הוא יקרא לעזרה מרכיב האפליקציה [errorHandler|CErrorHandler] .

זריקת שגיאות חריגות (Exceptions)
------------------

זריקת שגיאות חריגות ב Yii אינה שונה מזריקת שגיאות חריגות ב PHP. ניתן להשתמש בתחביר הבא כדי לזרוק שגיאה חריגה בעת הצורך:

~~~
[php]
throw new ExceptionClass('ExceptionMessage');
~~~

Yii  מגדירה שני מחלקות עבור שגיאות חריגות: [CException] ו [CHttpException]. הקודמת היא מחלקה כללית לשגיאות חריגות, בזמן שהשנייה מייצגת שגיאה חריגה שצריכה להיות מוצגת למשתמשי הקצה. כמו כן השנייה מכילה מאפיין [statusCode|CHttpException::statusCode] המייצג את מספר הסטטוס של בקשת ה HTTP. המחלקה של השגיאה החריגה מחליטה כיצד להציגה, כפי שנסביר בהמשך.

» Tip|טיפ: זריקת שגיאה חריגה מסוג [CHttpException] הינה דרך פשוטה לדיוון על שגיאות שבוצעו על ידי פעולות לקויות של המשתמשים. לדוגמא, במידה והמשתמש הזין מספר הודעה לא תקני בקישור, אנו יכולים לבצע את הפעולה הבאה בכדי להציג שגיאה 404 (העמוד לא נמצא):

~~~
[php]
// אם מספר ההודעה לא תקני
throw new CHttpException(404,'העמוד שחפשת לא נמצא או לא קיים.');
~~~

הצגת שגיאות
-----------------

ברגע שהשגיאה מכוונת אל רכיב האפליקציה [CErrorHandler], הרכיב בוחר קובץ תצוגה מתאים להצגת השגיאה. במידה והשגיאה נועדה לתצוגה של משתמשים, כמו למשל [CHttpException], הרכיב משתמש בקובץ תצוגה בשם `errorXXX`, כש `XXX` מייצג את סטטוס השגיאה של HTTP (למשל 400, 404, 500). במידה והשגיאה הינה פנימית וצריך להציגה רק למפתחים, קובץ תצוגה בשם `exception` יכנס לשימוש במקום. במקרה השני, תוצג השגיאה המדוייקת שהתרחשה ואיפה זה קרה בידיוק בקבצים.

» Info|מידע: בזמן שהאפליקציה רצה במצב [תפוקתי (חי)](/doc/guide/basics.entry#debug-mode), כל השגיאות כולל את השגיאות הפנימיות יוצגו בעזרת קובץ תצוגה `errorXXX`. וזה מכיוון וקבצי התצוגה האחרים מכילים מידע רגיש שלא אמור להיות מוצג למשתמשי הקצה ולכן מופעל רק במצב פיתוח. במקרה זה, מפתחים צריכים להסתמך על תיעוד השגיאות בכדי לדעת מהו הגורם המדוייק לשגיאה.

[CErrorHandler] מאתר את קובץ התצוגה המתאים בסדר הבא:

   1. `WebRoot/themes/ThemeName/views/system`: זוהי תיקית המערכת - `system` תחת התבנית הנמצאת בשימוש כרגע.

   2. `WebRoot/protected/views/system`: זוהי תיקית המערכת - `system` ברירת המחדל של האפליקציה.

   3. `yii/framework/views`: זוהי תיקית המקור המגיע ביחד עם הפריימוורק של Yii.

לכן, במידה ואנו רוצים להתאים אישית את תצוגת השגיאות, אנו צריכים פשוט ליצור קבצי תצוגה עבור השגיאות תחת התיקיה `system` באפליקציה או תחת כל תבנית בה אנו משתמשים.
כל קובץ הינו קובץ PHP רגיל המכיל בעיקר קוד HTML. למידע נוסף, יש לעיין קבצי תצוגת השגיאות תחת התיקיה `view` בתיקיה בה נמצאים הקבצים של הפריימוורק.

### טיפול בשגיאות בעזרת פעולה

החל מגרסא 1.0.6, Yii מאפשר שימוש [בפעולה של קונטרולר](/doc/guide/basics.controller#action) בכדי לטפל בתצוגת השגיאות. בכדי לעשות זאת, אנו צריכים להגדיר את מנהל השגיאה בהגדרות האפליקציה בצורה הבאה:

~~~
[php]
return array(
    ......
    'components'=»array(
        'errorHandler'=»array(
            'errorAction'=»'site/error',
        ),
    ),
);
~~~

בקוד למעלה, אנו מגדירים את המאפיין [CErrorHandler::errorAction] לנתיב `site/error` אשר מכוון לפעולה `error` בקונטרולר `SiteController`. אנו יכולים להשתמש בניתוב שונה במידה וצריך.

אנו יכולים לכתוב את פעולת `error` בצורה הבאה:

~~~
[php]
public function actionError()
{
    if($error=Yii::app()-»errorHandler-»error)
        $this-»render('error', $error);
}
~~~

בפעולה, אנו קודם מקבלים את המידע המדוייק אודות השגיאה מהמאפיין [CErrorHandler::error]. במידה והוא לא ריק, אנו מציגים את קובץ התצוגה `error` ביחד עם המידע אודות השגיאה.
המידע אודות השגיאה החוזר מהמאפיין [CErrorHandler::error] הוא מערך המכיל את האלמנטים הבאים:

 * `code`: קוד הסטטוס של HTTP (לדוגמא 400, 404, 500)
 * `type`: סוג השגיאה (לדוגמא [CHttpException], `PHP Error`);
 * `message`: הודעת השגיאה;
 * `file`: שם קובץ ה PHP איפה שהתרחשה השגיאה;
 * `line`: מספר השורה בקובץ ה PHP היכן שהתרחשה השגיאה;
 * `trace`: רשימת הקבצים שהמערכת הריצה עד הגעתה לקובץ המכיל את השגיאה;
 * `source`: קוד המקור המכיל את השגיאה.

» Tip|טיפ: הסיבה שאנו בודקים אם המאפיין [CErrorHandler::error] הוא ריק היא מכיוון שהמשתמש יכול לבקש את הפעולה `error` ישירות ולהריץ אותה, ובמקרה זה לא תיהיה שגיאה.
מאחר ואנו מעבירים את המערך של `error$` ישירות לקובץ התצוגה, הוא אוטומטית מורחב למשתנים בודדים. כתוצאה מכך, בקובץ התצוגה אנו יכולים לגשת ישירות למשתנים כמו `code$` ו `type$`.

תיעוד הודעות
---------------

הודעה ברמה של `error` תמיד תתעוד ברגע שתתבצע שגיאה. במידה והשגיאה בוצעה על ידי אזהרה או התראה של PHP, ההודעה תתעוד תחת קטגוריה `php`, במידה והשגיאה בוצעה על ידי שגיאה חריגה שלא נתפסה, הקטגוריה תיהיה `exception.ExceptionClassName` (עבור שגיאות חריגות של המחלקה [CHttpException] קוד הסטטוס של השגיאה תחת המאפיין [statusCode|CHttpException::statusCode] יצורף גם הוא לשם הקטגוריה).
לכן ניתן להשתמש באפשרות [התיעוד](/doc/guide/topics.logging) בכדי לנטר שגיאות הקוראות במהלך הרצת האפליקציה.

«div class="revision"»$Id: topics.error.txt 1064 2009-05-26 00:15:33Z qiang.xue $«/div»